DigiLocker Fetch eAadhaar API

The following document highlights the details of the DigiLocker Fetch eAadhaar API.

API Description

Objective

The DigiLocker Fetch eAadhaar API retrieves the user's eAadhaar details from Digilocker.

Input	Output
A unique reference identifier	The eAadhaar details of the customer in a JSON response, including their name, date of birth, address, photo, and their gender

API URL

https://ind-verify.hyperverge.co/api/digilocker/eAadhaarDetails

API Endpoint

eAadhaarDetails

Overview

The DigiLocker Fetch eAadhaar API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Optional	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the DigiLocker Fetch eAadhaar API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
referenceId	Mandatory	string	The unique reference identifier	Not Applicable	Not Applicable
aadhaarFile	Mandatory	string	The parameter that fetches the customer's eAadhaar details	yes / no	Not Applicable
rawAddressFields	Optional	string	The parameter that controls address formatting in the response. When set to "yes", the API adds an addressFields object in the response with the user's address segregated into relevant fields. When set to "no", the response contains only the address field with the user's address as a single string value	yes / no	no
returnYob	Optional	string	The parameter that controls whether year of birth (yob) is returned in the response. When set to "yes", the API adds a yob field in the response with the user's year of birth. When set to "no", the response contains only the dob field with the user's date of birth as received from DigiLocker info The format of Date of Birth in the response matches the eAadhaar format; either DD/MM/YYYY or year only (YYYY), depending on what is displayed in the eAadhaar.	yes / no	no
returnFatherName	Optional	string	The parameter that controls whether the father's name is returned in the response. When set to "yes", the API adds a fatherName field in the response with the user's father's name	yes / no	no
signedImage	Optional	string	The parameter that controls whether a signed photo URL is returned in the response. When set to "yes", the API adds a signedPhotoFile field in the response with the user's S3 pre-signed URL photo	yes / no	no
useV2StorageLocation	Optional	string	The parameter that enables dashboard visibility and controls aadhaar file URL expiry. When set to "yes", you can view the data in the dashboard and the aadhaar file URL expiry will be set for three hours	yes / no	no
blockMinors	Optional	string	The parameter that controls whether minor accounts are blocked. When set to "yes", the API returns a 400 response denoting the digilocker account belongs to a minor	yes / no	no
returnCreatedTimeStamp	Optional	string	The parameter that controls whether the created timestamp is returned in the response. When set to "yes", the API returns the epoch timestamp in milliseconds for the created timestamp of the aadhaar file	yes / no	no
aadhaarFileGenerationChannel	Optional	string	The parameter that controls the formatting of the aadhaar file. Based on the values passed (default or cvl), the formatting of the aadhaar file changes	default / cvl	default
returnUserConsentError	Optional	string	The parameter that controls whether a 400 error is returned when consent is not provided. When set to "yes", the API returns a 400 error in case consent is not provided by the user to access the Digilocker account	yes / no	no
returnSummary	Optional	string	The parameter that controls whether a summary key is returned in the response. When set to "yes", the API adds a summary key in the response	yes / no	no

Request

The following code snippet demonstrates a standard curl request for the DigiLocker Fetch eAadhaar API:

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/eAadhaarDetails' \
--header 'Content-Type: application/json' \
--header 'appID: <Enter_the_HyperVerge_appId>'\
--header 'appKey: <Enter_the_HyperVerge_appKey>'\
--header 'transactionID: <Enter_the_HyperVerge_transactionID>' \
--data-raw '{
    "referenceId" : "<Reference_ID>",
    "aadhaarFile" :"yes"
}'

Success Response

The following code snippet demonstrates a success response from the DigiLocker Fetch eAadhaar API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "name": "<Name_of_the_User>",
    "dob": "<Date_Of_Birth_from_eAadhaar>",
    "address": "<Address_Of_The_User>",
    "maskedAadhaarNumber": "<Masked_Aadhaar_Number>",
    "photo": "<Base64_Image_Of_The_Users_Profile_Photo>",
    "addressFields": {
      "co": "<Care_Of_Field>",
      "country": "<Country>",
      "district": "<District>",
      "subDistrict": "<Subdistrict>",
      "postOffice": "<Post_Office>",
      "house": "<House_Number>",
      "locality": "<Locality>",
      "pincode": "<Pincode>",
      "state": "<State>",
      "street": "<Street>",
      "vtc": "<Village_Town_City>",
      "landmark": "<Landmark>"
    },
    "gender": "<Gender>",
    "aadhaarFile": "<Link to aadhaar file>",
    "xmlAadhaarFile" : "<link to xml aadhaar file>",
    "createdTimeStamp": "1737033755319", //returned when returnCreatedTimeStamp is enabled
     "summary": {
            "action": "pass",
            "details": []
        }
  }
}

Success Response Details

The following table outlines the details of the success response from the DigiLocker Fetch eAadhaar API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the eAadhaar details
result.name	string	The name of the customer
result.dob	string	The date of birth of the customer
result.address	string	The address of the customer
result.maskedAadhaarNumber	string	The masked Aadhaar number of the customer
result.photo	string	The base64 string of the customer's profile photo
result.summary	object	The object containing summary information. This field is returned when returnSummary is set to "yes"
result.summary.action	string	The action status in the summary
result.summary.details	array	The array containing summary details
result.addressFields	object	The object containing segregated address fields
result.addressFields.co	string	The care of field in the address
result.addressFields.country	string	The country in the address
result.addressFields.district	string	The district in the address
result.addressFields.subDistrict	string	The subdistrict in the address
result.addressFields.postOffice	string	The post office in the address
result.addressFields.house	string	The house number in the address
result.addressFields.locality	string	The locality in the address
result.addressFields.pincode	string	The pincode in the address
result.addressFields.state	string	The state in the address
result.addressFields.street	string	The street in the address
result.addressFields.vtc	string	The village, town, or city in the address
result.addressFields.landmark	string	The landmark in the address
result.gender	string	The gender of the customer
result.aadhaarFile	string	The S3 URL for the Aadhaar file
result.xmlAadhaarFile	string	The link to the XML Aadhaar file
result.createdTimeStamp	string	The epoch timestamp in milliseconds for the created timestamp of the aadhaar file. This field is returned when returnCreatedTimeStamp is set to "yes"

Error Responses

The following are some error responses from the DigiLocker Fetch eAadhaar API:

Missing Mandatory Input

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "referenceId is required"
  }
}

Invalid Reference ID

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_INVALID_REFID",
    "message": "Please try verifying the refId"
  }
}

User Cancelled Transaction

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_USER_DIGILOCKER_USER_CANCELLED",
    "message": "user cancelled the transaction"
  }
}

User Rejected Consent

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_USER_DIGILOCKER_ACCESS_CONSENT_MISSING",
    "message": "consent not provided by user to access digilocker"
  }
}

Document Consent Missing

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_CONSENT_MISSING",
    "message": "consent not provided by user for the document."
  }
}

Minor Account

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_MINOR_ACCOUNT",
    "message": "Entered details belongs to a minor"
  }
}

Aadhaar Not Linked

{
  "status": "failure",
  "statusCode": "422",
  "error": {
    "code": "ER_AADHAAR_NOT_LINKED",
    "message": "Aadhaar is not linked to the account"
  }
}

aadhaar Data Unavailable

{
  "status": "failure",
  "statusCode": "422",
  "error": {
    "message": "Aadhaar data is not available for this user. Please perform Aadhaar eKYC again",
    "code": "ER_AADHAAR_NOT_AVAILABLE"
  }
}

Service Unresponsive

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_UNRESPONSIVE",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Service Unpublished

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_UNPUBLISHED",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Service Inactive

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_INACTIVE",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Service Configuration Error

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_CONFIGERROR",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Service Response Error

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_RESPERROR",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Service Exception

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_REPO_SERVICE_EXCEPTION",
    "message": "Error Connecting to digilocker. Please try again after sometime."
  }
}

Digilocker Error

{
  "status": "failure",
  "statusCode": "504",
  "error": {
    "code": "ER_DIGILOCKER_UNABLE_TO_FETCH_DATA",
    "message": "Digilocker unable to fetch data from UIDAI.Please try starting the process again"
  }
}

Missing or Invalid Credentials

{
  "status": "failure",
  "statusCode": "401",
  "error": "Missing/Invalid credentials"
}

Expired Token

{
  "status": "failure",
  "statusCode": "401",
  "error": {
    "code": "ER_EXPIRED_TOKEN",
    "message": "Session has expired."
  }
}

Rate Limit Exceeded

{
  "status": "failure",
  "statusCode": "429",
  "error": "Requests rate limit exceeded"
}

Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "Something went wrong"
  }
}

Error Response Details

A failure or error response contains a failure status with a relavant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	referenceId is required	The mandatory referenceId parameter is missing from the request	Provide valid referenceId in the request
400	Please try verifying the refId	The provided referenceId is invalid	Verify and provide a valid referenceId
400	user cancelled the transaction	The user cancelled the transaction during the DigiLocker authentication process	Please try again or contact the user
400	consent not provided by user to access digilocker	The user rejected consent to access their DigiLocker account	Please ensure user provides consent or try again
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
401	Session has expired.	The user's DigiLocker session has expired. This error typically occurs in the following scenarios: The DigiLocker consent flow was not completed properly before attempting to fetch Aadhaar details The callback URL configuration is incorrect, preventing proper redirection and session establishment	Ensure the complete DigiLocker consent flow is followed before calling the Aadhaar details endpoint Verify that the callback URL is configured correctly to enable proper redirection If this error persists despite following the steps above, please contact our support team at support@hyperverge.co
422	Aadhaar is not linked to the account	The user's Aadhaar is not linked to their DigiLocker account	Please ensure the user links their Aadhaar to DigiLocker
422	Aadhaar data is not available for this user. Please perform Aadhaar eKYC again	Aadhaar data is unavailable for the user	Please perform Aadhaar eKYC again
500	Something went wrong	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution
504	Error Connecting to digilocker. Please try again after sometime.	DigiLocker service is unresponsive, unpublished, inactive, or has configuration/response/exception errors	Please try again after sometime or contact the HyperVerge team
504	Digilocker unable to fetch data from UIDAI.Please try starting the process again	DigiLocker was unable to fetch data from UIDAI	Please try starting the process again